Finding Geometric Information About a Shape (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 4 - Geometric Operations / Using Geometric Operations

Finding Geometric Information About a Shape
QuickDraw GX provides a number of functions that allow you to determine geometric information about a shape, such as the length of a contour or the area covered by a shape.
The sample function in Listing 4-7 creates a path shape with two concentric contours, the outer contour having a clockwise contour direction and the inner contour having a counterclockwise contour direction. This path shape is used in subsequent sections to illustrate the geometric information functions.
Listing 4-7 Creating a path shape with two contours having opposite contour directions
void CreateConcentricCircles(void)
{
   gxShape aPathShape;

   static long twoCircleGeometry[] = {2, /* number of contours */
                                      4, /* number of points */
                                      0xF0000000, /* 1111 ... */
                                      ff(50), ff(50),   /* off */
                                      ff(150), ff(50),  /* off */
                                      ff(150), ff(150), /* off */
                                      ff(50), ff(150),  /* off */
                                      4, /* number of points */
                                      0xF0000000, /* 1111 ... */
                                      ff(65), ff(135),  /* off */
                                      ff(135), ff(135), /* off */
                                      ff(135), ff(65),  /* off */
                                      ff(65), ff(65)};  /* off */


   aPathShape = GXNewPaths((gxPaths *) twoCircleGeometry);

   GXDrawShape(aPathShape);
   GXDisposeShape(aPathShape);
}
The resulting shape geometry is shown in Figure 4-33.
Figure 4-33 A path with an outer clockwise contour and an inner counterclockwise contour

Finding the Length of a Contour
QuickDraw GX provides the GXGetShapeLength function so you can measure the length of a contour. This function takes three parameters: a reference to the shape containing the contour you want to measure, an index indicating which contour you want to measure, and a pointer to a variable of type gxWide to store the result.
For example, if you add the declaration
gxWide length;
and the function call
GXGetShapeLength(aPathShape, 1, &length);
to the sample function in Listing 4-7, the value returned in the length parameter is approximately 322.543, which is the length (the circumference) of the outer contour.
For more information about the GXGetShapeLength function, see page 4-83.

Finding the Point at a Certain Distance Along a Contour
QuickDraw GX provides the GXShapeLengthToPoint function that allows you to calculate the position of the point that falls at a specified distance along a contour. This function also calculates the tangent of the contour at that point.
As an example, adding the function call
GXShapeLengthToPoint(aPathShape, 1, ff(120), 
                     &thePoint, &theDirection);
to the sample function in Listing 4-7 determines the point that falls along the first contour at a distance of 120.0 points from the start of the contour, and stores the resulting point in the thePoint parameter. Also, in the theDirection parameter, this function stores a tangent vector indicating the direction of the contour at that point.
The result of this function is shown in Figure 4-34.
Figure 4-34 Finding a specified point on a path contour

For more information about the GXShapeLengthToPoint function, see page 4-85.

Finding the Bounding Rectangle and Center Point of a Shape
QuickDraw GX provides functions for finding the bounding rectangle of a shape and the center point of a shape. The bounding rectangle is the smallest rectangle that contains the shape. The center point of a shape is not the center of the shape's bounding rectangle; rather it is the "center of gravity" of a shape. QuickDraw GX guarantees that the center point of a shape remains the same even if the shape is rotated.
You can use the GXGetShapeBounds function to find the bounding rectangle of a shape. As an example, if you apply the function
GXGetShapeBounds(aPathShape, 0, &theBounds);
to the path shape from Listing 4-7, the result is a rectangle with the coordinates (50.0, 50.0, 150.0, 150.0). Similarly, if you apply the function
GXGetShapeCenter(aPathShape, 0, &thePoint);
to the same path shape, the result is the point: (100.0, 100.0).
The results of these functions are depicted in Figure 4-35.
Figure 4-35 Finding the bounding rectangle and the center point of a path

If you move the inner contour of the path shape to right, the center point moves to the right as well, effectively moving with the combined "center of gravity" of the two contours, as shown in Figure 4-36.
Figure 4-36 Finding the center point of two contours

Notice that the center point lies somewhere between the center of the outer contour and the center of the inner contour.
For more information about the GXGetShapeBounds function, see page 4-90. For more information about the GXGetShapeCenter function, see page 4-87.

Finding the Area of a Shape
QuickDraw GX provides the GXGetShapeArea function so you can determine the area covered by a shape.
With the path shape from Listing 4-7 (on page 4-41), applying the function
GXGetShapeArea(aPathShape, 1, &theArea);
results in the value 4250.0. This value represents the area of the outer contour minus the area of the inner contour, as shown in Figure 4-37.
Figure 4-37 Finding the area of a path, two contours with same contour direction

In effect, the function finds the area covered by the shape as if it were filled with the winding shape fill.
Therefore, if you reverse the direction of the inner contour of this path with the function call
GXReverseShape(aPathShape, 2);
then the function call
GXGetShapeArea(aPathShape, 1, &theArea);
results in the value 12416.6666. This value represents the area of the outer contour plus the area of the inner contour--the area covered by the inner contour is counted twice.
The area included in this calculation is depicted in Figure 4-38.
Figure 4-38 Finding the area of a path, two contours with opposite contour direction

Note that the GXGetShapeArea function does not consider the shape fill when calculating area--it includes this overlapping area twice whether the shape fill is winding fill, even-odd fill, open-frame fill, or closed-frame fill.
You can correct this calculation by calling the GXSimplifyShape function first. For example, if you set the shape fill to winding fill with the function call
GXSetShapeFill(aPathShape, gxWindingFill);
and then call the GXSimplifyShape function:
GXSimplifyShape(aPathShape);
the GXSimplifyShape function removes the inner contour, as shown in Figure 4-39.
Figure 4-39 Finding the area of a simplified path

Once this inner contour is removed, you can call the GXGetShapeArea function, and the area of the original outer contour (8333.3333) is returned.
For more information about the GXGetShapeArea function, see page 4-88.